<!--
  ~ Copyright (C) 2010 Brockmann Consult GmbH (info@brockmann-consult.de)
  ~
  ~ This program is free software; you can redistribute it and/or modify it
  ~ under the terms of the GNU General Public License as published by the Free
  ~ Software Foundation; either version 3 of the License, or (at your option)
  ~ any later version.
  ~ This program is distributed in the hope that it will be useful, but WITHOUT
  ~ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  ~ FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
  ~ more details.
  ~
  ~ You should have received a copy of the GNU General Public License along
  ~ with this program; if not, see http://www.gnu.org/licenses/
  -->

<html>
<head>
    <title>Sentinel Toolbox Help - Vector Data Management</title>
    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
    <link rel="stylesheet" href="../style.css">
</head>

<body>
<table class="header">
    <tr class="header">
        <td class="header">&nbsp;Vector Data Management</td>
        <td class="header" align="right"><a href="../general/overview/SnapOverview.html"><img src="../images/snap_header.jpg"
                                                                                     border="0"></a></td>
    </tr>
</table>

<h2>The Vector Data Concept</h2>

In addition to the bands and tie-point grids contained in satellite data products - which are all kinds
of <i>raster data</i> - the SNAP product model also features <i>vector data</i>.

Thus, vector data are stored to and restored to from <a href="../general/overview/BeamDimapFormat.html">BEAM-DIMAP</a> product
files. A product can comprise any number of named <i>vector data containers</i>. Each container may virtually comprise
any number of vector data nodes.

There are two general occurrences of vector data in the Sentinel Toolbox: <b>geometries</b> and <b>correlative</b> data. Both of these
concepts are thoroughly described below.

<h3>1) Geometries</h3>

<table>
    <tr>
        <td style="border-width:0">
            Geometries are points, lines, multilines, polygons, or multipolygons. New geometries are always added to
            the geometry container selected in the <b>Vector Data</b> node of the
            <a href="ProductExplorer.html">Products View</a> tool window as shown in the screenshot. If there isn't a
            single geometry container yet, SNAP will create a default container named <b>geometry</b>.<br/>
           <!--
            (This default behaviour can be customized in the Sentinel Toolbox configuration file
            <code>${S3TBX_HOME}/config/s3tbx.config</code>.) -->
        </td>
        <td style="border-width:0">
            <img src="images/ProductsViewWithGeometry.png" alt="Products view with geometries">
        </td>
    </tr>
</table>

<h4>Relationship with Masks and ROIs</h4>

<p>
    The geometries in a geometry container can be directly used as a ROI for raster data analysis.
    Once a new geometry container has been added to the data product, an associated <i>geometry mask</i> is created by
    rendering the geometry onto the product's intrinsic raster data grid.
</p>

<div align="center">
    <table>
        <tr>
            <td style="border-width:0"><img src="images/GeometryPlain.png" alt="Geometry Plain"></td>
            <td style="border-width:0"><img src="images/Geometry.png" alt="Geometry"></td>
        </tr>
        <tr>
            <td style="border-width:0" align="center">Polygon geometry (vector data)</td>
            <td style="border-width:0" align="center">Resulting mask (raster data)</td>
        </tr>
    </table>
</div>
<p>
    The associated mask will always have the
    same name as the geometry container which created it and can serve as possible mask for the selected band or
    tie-point
    grid without any additional user interaction.
    Once the geometry is created (e.g. simply by drawing it, see below), its associated geometry mask can be used as ROI
    in the various analysis tools, such as the <a href="StatisticsDialog.html">Statistics</a>,
    <a href="HistogramDialog.html">Histogram</a>, and <a href="DensityPlotDialog.html">Scatter Plot</a> tool windows.
    Multiple geometries can be defined by creating new geometry containers as described below.
</p>

<h4>Creating a new geometry</h4>

<p>
    Once an image view is opened, new geometries are created by using the various drawing tools provided by
    the Sentinel Toolbox through the <b>Interactions Toolbar</b>:
</p>

<table>
    <tr>
        <td style="border-width:0"><img src="images/icons/DrawLineTool24.gif" alt="Line"></td>
        <td style="border-width:0"><b>Line</b>: Press left mouse button for the start point, drag line to end point and
            release left mouse button.
        </td>
    </tr>
    <tr>
        <td style="border-width:0"><img src="images/icons/DrawPolylineTool24.gif" alt="Polyline"></td>
        <td style="border-width:0"><b>Polyline</b>: Single-click (press and release) left mouse button for the start
            point, move line segment and click to add a
            vertex point, move to end point and double-click to finalize the polyline.
        </td>
    </tr>
    <tr>
        <td style="border-width:0"><img src="images/icons/DrawRectangleTool24.gif" alt="Rectangle"></td>
        <td style="border-width:0"><b>Rectangle</b>: Press left mouse button for the start point, drag line to end point
            and release left mouse button.
        </td>
    </tr>
    <tr>
        <td style="border-width:0"><img src="images/icons/DrawEllipseTool24.gif" alt="Ellipse"></td>
        <td style="border-width:0"><b>Ellipse</b>: Similar to rectangle; Press left mouse button for the start point,
            drag line to end point and release left
            mouse button.
        </td>
    </tr>
    <tr>
        <td style="border-width:0"><img src="images/icons/DrawPolygonTool24.gif" alt="Polygon"></td>
        <td style="border-width:0"><b>Polygon</b>: Similar to polyline; Single-click (press and release) left mouse
            button for the start point, move
            line segment and click to add a vertex point, move to end point and double-click to close the polygon.
        </td>
    </tr>
</table>

<p></p>


<h4><a name="CreateGeometryContainer">Creating a new geometry container</a></h4>

<p>
    Use the menu item <b>Vector/New Vector Data Container</b> to create a new geometry container.
</p>

<table>
    <tr>
        <td style="border-width:0"><img src="images/icons/NewVectorDataNode24.gif" alt="Container"></td>
        <td style="border-width:0">Clicking the button opens a dialog for creating a new geometry container.
            The user is prompted to enter a unique name for the new container.
        </td>
    </tr>
</table>


<h4>Editing geometries</h4>

<p>
    Geometries may be edited in a number of ways once they have been selected. Note that editing or deleting a geometry
    will automatically affect the mask associated with the geometry's container.
    Use the <b>Select</b> tool to select geometries which shall be edited:
</p>

<table>
    <tr>
        <td style="border-width:0"><img src="images/icons/SelectTool24.gif" alt="Select"></td>
        <td style="border-width:0">Select a single geometry by clicking it. Select one or more geometries by dragging a
            selection
            rectangle around them. Hold down the <b>control</b> key while selecting in order to add or remove
            geometries from the current selection set.
        </td>
    </tr>
</table>

<p>Clicking selected geometries multiple times lets them step through a number of selection modes allowing for different
    editing modes which are further described below.
</p>

<table>
    <tr>
        <td style="border-width:0"><img src="images/GeometrySelMode1.png" alt="Geometry Selection Mode 1"></td>
        <td style="border-width:0"><img src="images/GeometrySelMode2.png" alt="Geometry Selection Mode 2"></td>
        <td style="border-width:0"><img src="images/GeometrySelMode3.png" alt="Geometry Selection Mode 3"></td>
    </tr>
    <tr>
        <td style="border-width:0" align="center">Selection mode 1</td>
        <td style="border-width:0" align="center">Selection mode 2</td>
        <td style="border-width:0" align="center">Selection mode 3</td>
    </tr>
</table>


<p>
    <b>Move:</b> Selected shapes can be moved to another location simply by dragging them with the mouse.
</p>

<p>
    <b>Move vertex:</b> If single selected geometries are clicked once again, the selection mode changes depending on
    the
    geometry type. The first mode allows the user to move the vertexes of lineal and polygonal geometries by dragging
    the
    appearing
    vertex handles.
</p>

<p>
    <b>Add vertex:</b> New vertexes can be inserted by pressing the <b>Control</b> key while clicking an existing
    vertex.
    The new vertex can now be dragged to its final location.
</p>

<p>
    <b>Remove vertex:</b> Existing vertexes can be removed by dragging them onto their predecessor or successor vertexes
    by again pressing the <b>Control</b> key.
</p>

<p>
    <b>Scale:</b> The next selection mode (click again) allows the user to scale the size of a geometry by dragging the
    appearing size handles.
</p>

<p>
    <b>Cut, Copy, Paste:</b> Use these commands from the <b>Edit</b> menu or use the keys <b>Control X</b>,
    <b>Control C</b>, <b>Control V</b> to cut or copy geometries into the operating system's clipboard and
    to paste them into the same or another view.
</p>

<p>
    <b>Delete:</b> Use the command from the <b>Edit</b> menu or use the <b>Delete</b> key.
    Mac-users can use <b>fn</b> + <b>Backspace</b> alternatively.
</p>

<h3>2) Correlative Data</h3>

<p>
    The Sentinel Toolbox considers vector data that does not originate from satellite data as <i>correlative data</i>.
    The Toolbox supports exploiting of correlative data in some ways, for examples see the help for the
    <a href="ProfilePlotDialog.html">Profile Plot</a> dialog or the
    <a href="CorrelativePlotDialog.html">Correlative Plot</a> dialog.
</p>

<h4>Pins and Ground Control Points (GCP)</h4>

<p>
    Pins and Ground Control Points are vector data treated as point geometries. Thus, geometry editing such as moving or
    deleting is the same as for other geometries as described above in chapter 'Working with Geometries'. Despite this,
    the pins and GCPs of a data product are still managed as described in
    <a href="PinManagement.html">Pin Management</a> and <a href="GcpManagement.html">GCP Management</a>, respectively.
</p>

<h4>Vector data import</h4>

<p>
    There are several built-in strategies for importing vector data into the Sentinel Toolbox:
    <ol>
        <li>Import ESRI shapefiles (see below)</li>
        <li>Import generic correlative data from CSV files (see <a href="ImportCSV.html">here</a>)</li>
        <li>Import SeaDAS ship tracks (see <a href="ImportSeaDASTrack.html">here</a>)</li>
        <li>Import Mermaid data (see <a href="ImportMermaid.html">here</a>)</li>
    </ol>
</p>

<p>
    The <a href="ImportShapefile.html">Import Shapefile</a> command allows the user to import geometries from <i>ESRI
    Shapefiles(*.shp)</i>: Multiple geometries can be imported from a Shapefile.
    The geometry coordinates used in the Shapefile will be converted to the coordinates reference system used by the
    current data product. Note that the Sentinel Toolbox does only offer limited support regarding the various style settings which
    may be attached to a specific Shapefile. It also currently ignores all the attribute data that usually
    come with a Shapefile. This may change in later SNAP versions.
</p>

<hr>
</body>
</html>